<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="tutorial.css">
<TITLE>
Data Structures
</TITLE>
</HEAD>
<BODY >
<A HREF="tutorial003.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H1 CLASS="chapter"><A NAME="htoc25">Chapter&nbsp;3</A>&nbsp;&nbsp;Data Structures</H1><UL>
<LI><A HREF="tutorial004.html#toc11">External data representation</A>
<LI><A HREF="tutorial004.html#toc12">Internal data representation</A>
</UL>

<A NAME="datastructures"></A>
In this chapter we discuss the choice of data structures for the different application parts. Next to the top-level design, this is the most important aspect that must be specified correctly right from the beginning of a project. The wrong choice of a data structure may mean significant re-work in order to change some deficiency later on, while on the other hand a good data structure design can simplify the coding process and can lead to a very efficient implementation.<BR>
<BR>
<A NAME="toc11"></A>
<H2 CLASS="section"><A NAME="htoc26">3.1</A>&nbsp;&nbsp;External data representation</H2>
The first question is how the data <A NAME="@default56"></A>will be fed to the application. We can distinguish five alternatives.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>arguments</B><DD CLASS="dd-description"> In the first alternative, all data are passed in arguments to the query. Multiple items of the same type will usually be represented as lists, with structures to hold different attributes of the different objects. This form has the advantage that each query can be run with a completely new data set without changing the database or creating a new set of files. But debugging data in this form can be more difficult, as there is not direct way to look up some data item. This method also requires work on the Java side to build all the data structures before a call to the ECLiPSe solver. A similar effort is required to develop testing code written in ECLiPSe which exercises the interface.<BR>
<BR>
<DT CLASS="dt-description"><B>data files</B><DD CLASS="dd-description"> The second alternative is to use data files in a fixed format. The ECLiPSe program then has to read these files and build the internal data structures at the same time. Depending on the format, this may require parsing the input format with definite clause grammars (DCG) <A NAME="@default57"></A><A NAME="@default58"></A>(see section <A HREF="tutorial007.html#howtousedcgs">6.2</A>), adding to the development effort<SUP><A NAME="text5" HREF="#note5">1</A></SUP>. But as the files can be read and written easily, it is quite simple to create test data sets and to analyze problems by hand. The design for the fixed format may require some extra effort if we want to use the full character set for atoms and strings. A proper quoting mechanism may be required in order to distinguish say a comma separator from a comma contained inside a data field.<BR>
<BR>
<DT CLASS="dt-description"><B>prolog terms</B><DD CLASS="dd-description"> The third alternative is to use data files as before, but to format them as valid Prolog terms <A NAME="@default59"></A>that can directly read with the ECLiPSe term I/O predicates. This avoids the overhead of writing parsers in ECLiPSe, but may be difficult for the calling side of the application, unless that is also written in ECLiPSe. Note that we again may face quoting problems, in particular for single and double quotes.<BR>
<BR>
<DT CLASS="dt-description"><B>EXDR</B><DD CLASS="dd-description"> ECLiPSe also provides a binary data format called EXDR that can be used to exchange information. This can be generated and parsed quite easily in ECLiPSe and in Java, and often allows significant space savings. In addition, problems with quoting are avoided. A disadvantage is that EXDR files are not directly readable by humans, and so may require extra effort during debugging. <BR>
<BR>
<DT CLASS="dt-description"><B>facts</B><DD CLASS="dd-description"> The last alternative is to store the data as facts <A NAME="@default60"></A>in the application. They can then be accessed from any part of the ECLiPSe code quite easily. Testing the code is simple by compiling some data files into the system. The Java interface can also store facts into the database quite easily. But changing the data for a new query can be rather complex, and may require recompiling some data modules.</DL>
We should note that instead of using files we can also build queues between the ECLiPSe and the Java parts of the application, avoiding the need for file system space.<BR>
<BR>
Which of these methods should be used? This depends on the application. Passing data as arguments clearly is the cleanest way, but requires significant work on the interface and on code for testing. Using data files in fixed formats is simple if the format is defined correctly, but its use of the file system can cause problems when multiple queries should be run concurrently on the same machine. Using Prolog terms in data files has the same disadvantage, but is very simple to use if different ECLiPSe systems exchange data. EXDR files are the safest form to store data, but also the least intuitive. Using queues instead of files avoids problems with multiple instances running at the same time, but require some form of logging to allow debugging. Using facts is a valid alternative if most of the data do not change from one query to the next, but requires extra work to reclaim memory after each change. The following table tries to summarize the advantages and disadvantages of each method.
<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=left NOWRAP>Property</TD>
<TD ALIGN=right NOWRAP>Argument</TD>
<TD ALIGN=right NOWRAP>Data file</TD>
<TD ALIGN=right NOWRAP>Terms</TD>
<TD ALIGN=right NOWRAP>Facts</TD>
<TD ALIGN=right NOWRAP>EXDR</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Multiple runs</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Debugging</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>-</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Test generation effort</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>-</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Java I/O effort</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>ECLiPSe I/O effort</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>++</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Memory</TD>
<TD ALIGN=right NOWRAP>++</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>- -</TD>
<TD ALIGN=right NOWRAP>-</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Development effort</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>-</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>+</TD>
<TD ALIGN=right NOWRAP>-</TD>
</TR></TABLE>
<BR>
<BR>
<DIV CLASS="center">Table 3.1: <A NAME="Data representation"></A>Data representation</DIV><BR>
<BR>

<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<A NAME="toc12"></A>
<H2 CLASS="section"><A NAME="htoc27">3.2</A>&nbsp;&nbsp;Internal data representation</H2>
The next question is how the data should be represented inside <A NAME="@default61"></A>the application. For this purpose we will have to introduce data structures<A NAME="@default62"></A> which allow rapid access to information, which deal with multiple data sets in different parts of the application and where we can add information in a structured way. It should be clear that the built-in fact data base cannot be used for this purpose. Instead, we have to pass the information via arguments of the predicates. In the following sections, we will discuss how the data should be structured to simplify access and coding.<BR>
<BR>
Note that all our data structures use <I>single assignment</I><A NAME="@default63"></A>, i.e. there is no destructive assignment<A NAME="@default64"></A> in the language<SUP><A NAME="text6" HREF="#note6">2</A></SUP>. Instead of removing<A NAME="@default65"></A><A NAME="@default66"></A><A NAME="@default67"></A> or changing elements of a structuce, we will always make a near-copy with some information being removed or changed. <BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc28">3.2.1</A>&nbsp;&nbsp;Named structures</H3>
The principal data representation feature of ECLiPSe are named structures<A NAME="@default68"></A><A NAME="@default69"></A>. These are terms were each argument is linked to an argument name. We can access one or more of the arguments with the <I>with</I><A NAME="@default70"></A> operator. Named structures are very similar to structures in other languages, the arguments of the structure correspond to attributes of the entity represented. Different attributes can have different types, so that we can store diverse information in a named structure.<BR>
<BR>
In order to use a structure, it must be defined with a <I>struct</I><A NAME="@default71"></A> definition. We can define a structure either <I>local</I><A NAME="@default72"></A> to a module or <I>export</I> <A NAME="@default73"></A>the definition so that the same structure can be used in other modules which import the definition. As part of a systematic design we normally create a module which contains nothing but exported structure definitions. This module is then imported with a <I>use_module</I><A NAME="@default74"></A> directive in all other modules of the application which use the structures. If a structure is used in one module only, we should define it as a local structure in that module.<BR>
<BR>
We also use comment directives to document the named structures, just like we do for exported predicates. For each attribute name, we define the data type of the attribute. Normally, these will be atomic data types <A NAME="@default75"></A>(integer, real, atom, string), but that is not required. The attribute can hold any data type that we can pass as an argument to a predicate. <BR>
<BR>
As an example of a named structure we use a small part of the RiskWise module <I>flow_structures</I><A NAME="@default76"></A>. 
<PRE CLASS="verbatim">
:-comment(struct(group),[
summary:"
this data structure describes the group object
",
fields:[
"name":"atom, name of the group",
"type":"atom, one of pop, interconntion, vpn or tariff_class",
"index":"integer, unique index of the group",
"list":"list of interface indices belonging to the group",
"nodes":"list of nodes which contain interfaces of that group"
]
]).
:-export struct(group(name,
                      type,
                      index,
                      list,
                      nodes)).
</PRE>

<H3 CLASS="subsection"><A NAME="htoc29">3.2.2</A>&nbsp;&nbsp;Placeholder variables</H3>
<A NAME="@default77"></A>If we do not specify a fixed attribute value when the named structure is created, then its value will be a free variable which can be bound later on. This is useful for two main purposes. On one side we can define attributes of a structure which will hold the constraint variables<A NAME="@default78"></A> of a problem, on the other side we can leave some attributes initially unassigned so that we can fill these slots with results of a computation later on.<BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc30">3.2.3</A>&nbsp;&nbsp;Nested structures vs. key lookup</H3>
<A NAME="@default79"></A><A NAME="@default80"></A>A very common data representation problem is how to access information about some structure from another structure, for example in RiskWise how to access the information about a router from an interface of the router. There are two main alternatives. The first is to insert the data of the first entity (router) directly in the representation of the second entity (interface) as an additional attribute, the second is to store a key which can be used to look up the entity. Although the first method has the advantage of avoiding the extra lookup, we do not recommend this approach. If we have recursive references to objects (in our example above if the router also contains a link to all its interfaces) then this direct representation becomes an infinite data structure, which causes problems for printing and debugging. If we use the second approach, we obviously need a way to find the entity belonging to a particular key without too much overhead. The choice of the key depends on the representation of our overall data structure, which we will discuss in the next sections.<BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc31">3.2.4</A>&nbsp;&nbsp;Lists</H3>
A natural way to represent a collection of items of the same type is to use lists<A NAME="@default81"></A>. They are very convenient to handle an arbitrary number of items by iterating on successive heads of the list, until the empty list is reached. Unfortunately, finding a particular item in a list is a very expensive operation, as we have to scan the list sequentially.<BR>
<BR>
We should never use a list when we can use a structure<A NAME="@default82"></A> instead. If we know that a collection will always have the same number of items (say 3), it is much better to use a structure with that number of arguments than to use a list. <BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc32">3.2.5</A>&nbsp;&nbsp;Hash tables</H3>
Hash tables<A NAME="@default83"></A> are a very useful alternative to lists, if we sometimes want to look up items rather than iterate over all of them. They are defined in the library <I>hash</I>.
We can add items one by one, without an a priori limit on the number of items.
As key <A NAME="@default84"></A>we can use numbers, atoms or arbitrary terms, but atoms would be the most common key in a hash table. This is very useful when converting input data, since the external data representation often will use names (atoms) to identify objects.<BR>
<BR>
While it is possible to iterate over all items of a hash table, this is not as simple as iteration over a list or an array.<BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc33">3.2.6</A>&nbsp;&nbsp;Vectors and arrays</H3>
Vectors<A NAME="@default85"></A> are another way to represent a collection of items. Each item is associated with an integer key in the range from 1 to <I>N</I>, where <I>N</I> is the size of the vector. Unfortunately, the value <I>N</I> must be known a priori, when we first create the vector. Accessing individual entries by index is very fast, and iterating over all entries is nearly as simple as for lists. The main drawbacks of a vector representation are that we have to know the total number of items beforehand and that the keys must be consecutive integers in the range from 1 to <I>N</I>.<BR>
<BR>
Multi-dimensional arrays <A NAME="@default86"></A>are simple nested vectors, they are created with the <I>dim</I> <A NAME="@default87"></A>predicate for a given dimension and size. Access to an element is with the <I>subscript</I><A NAME="@default88"></A> predicate (see section <A HREF="tutorial006.html#iterationonarray">5.5</A> for an example).<BR>
<BR>

<H3 CLASS="subsection"><A NAME="htoc34">3.2.7</A>&nbsp;&nbsp;Multi-representation structures</H3>
Each of the alternative representations given above has some advantages and disadvantages. To obtain a very flexible representation, we can choose a multi-representation structure<A NAME="@default89"></A>. In this structure, a collection of items is represented as a list and as a hash table and as an array. The list representation can be used for a very simple iteration over all items, the hash table is used in the initial data input phase to find items with a given name and the array of items is used in the core routines of the solver for the fastest access by an integer index. <BR>
<BR>
The memory requirements of this multi-representation scheme are quite low. The storage to hold the items themselves is shared for all representations, we only need the additional space for the list, hash table and array structures.<BR>
<BR>
In RiskWise<A NAME="@default90"></A>, we use the multi-representation scheme for most data structures, with special access predicates like <I>find_interface/3</I><A NAME="@default91"></A> to access items with either numeric indices or atom keys. References from one entity to another are by integer key, e.g. each interface structure contains as an attribute the integer key value of the node (router) to which it belongs.<BR>
<BR>
<HR WIDTH="50%" SIZE=1><DL CLASS="list"><DT CLASS="dt-list"><A NAME="note5" HREF="#text5"><FONT SIZE=5>1</FONT></A><DD CLASS="dd-list">ECLiPSEe 5.4 contains a freeware XML (http://www.xml.org) parser which handles most of the detail of parsing XML files. This makes the use of XML as a data exchange format for ECLiPSe are very exiting new possibility. The parser is described in the &#8220;Third Party Library&#8221; section of the reference manual.
<DT CLASS="dt-list"><A NAME="note6" HREF="#text6"><FONT SIZE=5>2</FONT></A><DD CLASS="dd-list">Destructive assignment in the hash library is hidden from the user.
</DL>
<HR>
<A HREF="tutorial003.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
